Add a "ref and sink" question. (#156865, Philip Langdale, text based on a

2004-11-01  Matthias Clasen  <mclasen@redhat.com>

	* gtk/question_index.sgml: Add a "ref and sink" question.
	(#156865, Philip Langdale, text based on a comment by Owen
	Taylor)

	* gtk/tmpl/gtkrc.sgml: Document im_module_file and settings
	assignments as toplevel statements.

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 7cb35eba9d90f754dee850b7a3caa7b84236ee49..37add64c52e630b92255548181274bdacf64cf78 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -4,9 +4,13 @@ Mon Nov  1 13:37:31 2004  Jonathan Blandford  <jrb@redhat.com>
 
 2004-11-01  Matthias Clasen  <mclasen@redhat.com>
 
+       * gtk/question_index.sgml: Add a "ref and sink" question.  
+       (#156865, Philip Langdale, text based on a comment by Owen
+       Taylor)
+
        * gtk/tmpl/gtkrc.sgml: Document im_module_file and settings
        assignments as toplevel statements.
-
+       
 2004-10-31  Matthias Clasen  <mclasen@redhat.com>
 
        * gtk/windows.sgml: s/PRETEND_WIN9X/G_WIN32_PRETEND_WIN9X/.

diff --git a/docs/reference/gtk/question_index.sgml b/docs/reference/gtk/question_index.sgml
index 9c027c948f8a15c3602ede09b344cca6c76179dd..d062c4e36c754316cfd14215cebe0f70967c5cdf 100644 (file)
--- a/docs/reference/gtk/question_index.sgml
+++ b/docs/reference/gtk/question_index.sgml
@@ -116,9 +116,51 @@ url="http://bugzilla.gnome.org">http://bugzilla.gnome.org</ulink>.)
 </para>
 
 </answer>
-
 </qandaentry>
 
+<qandaentry>
+<question>
+<para>
+Why does my program leak memory, if I destroy a widget immediately 
+after creating it ?
+</para>
+</question>
+
+<answer>
+<para>
+If <structname>GtkFoo</structname> isn't a toplevel window, then
+<informalexample><programlisting>
+ foo = gtk_foo_new (<!-- -->);
+ gtk_widget_destroy (foo);
+</programlisting></informalexample>
+is a memory leak, because no one assumed the initial floating 
+reference. If you are using a widget and you aren't immediately 
+packing it into a container, then you probably want standard 
+reference counting, not floating reference counting.
+</para>
+
+<para>
+To to get this, you must acquire a reference to the widget and drop the floating 
+reference (<quote>ref and sink</quote> in GTK+ parlance) after creating it:
+<informalexample><programlisting>
+ foo = gtk_foo_new (<!-- -->);
+ g_object_ref (foo); 
+ gtk_object_sink (GTK_OBJECT (foo));
+</programlisting></informalexample>
+When you want to get rid of the widget, you must call gtk_widget_destroy()
+to break any external connections to the widget before dropping your 
+reference:
+<informalexample><programlisting>
+ gtk_widget_destroy (foo); 
+ g_object_unref (foo); 
+</programlisting></informalexample>
+When you immediately add a widget to a container, it takes care of
+assuming the initial floating reference and you don't have to worry
+about reference counting at all ... just call gtk_widget_destroy()
+to get rid of the widget.
+</para>
+</answer>
+</qandaentry>
 
 <qandaentry>
 <question><para>
@@ -483,7 +525,7 @@ to the GNOME 2.0 platform</ulink>.
 <qandaentry>
 <question>
 <para>
-Why are types not registered if I use their <literal>GTK_TYPE_BLAH;</literal> macro ?
+Why are types not registered if I use their <literal>GTK_TYPE_BLAH</literal> macro ?
 </para>
 </question>
 

diff --git a/docs/reference/gtk/tmpl/gtkrc.sgml b/docs/reference/gtk/tmpl/gtkrc.sgml
index 55d2d1b5976d3781575647abb931e98571243d29..d09525ff438dd66dc46da292c677de13be26d246 100644 (file)
--- a/docs/reference/gtk/tmpl/gtkrc.sgml
+++ b/docs/reference/gtk/tmpl/gtkrc.sgml
@@ -219,7 +219,7 @@ The possible toplevel declarations are:
   </varlistentry>
 
   <varlistentry>
-    <term><replaceable>setting</replaceable> = <replaceable>value<replaceable></literal></term>
+    <term><replaceable>setting</replaceable> = <replaceable>value</replaceable></term>
     <listitem>
       <para>Specifies a value for a <link linkend="GtkSettings">setting</link>. Note that
         settings in RC files are overwritten by system-wide settings which are managed by